Network issue¶
Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.
What should I do if I cannot connect to the network?¶
Physical and data link layers (Ethernet cable/Wi-Fi/switch)¶
Symptom: After running ip a, the output does not show an IP address, or the network interface is shown as DOWN.
Common causes |
Solutions |
|---|---|
Ethernet cable is loose or damaged |
Reconnect the Ethernet cable and observe the Ethernet port LEDs. A steady green LED and a blinking yellow LED indicate data transmission. |
Wi-Fi is disconnected or the signal is weak |
Check the Wi-Fi configuration file (for example, /etc/wpa_supplicant.conf), or run nmcli dev wifi connect to reconnect. |
Switch or router port failure |
Use a different switch port, or connect the two devices directly with an Ethernet cable (a static IP address must be configured) to rule out an upstream network issue. |
Network interface driver is not loaded |
Run dmesg | grep -i eth or lspci to verify that the kernel has detected the network hardware. |
Network layer (IP address and subnet mask)¶
Symptom: After running ip a, the output shows an IP address, but the gateway does not respond to ping requests.
Common causes |
Solutions |
|---|---|
Incorrect IP address configuration (not on the same subnet) |
Check ip a for the configured IP address and subnet mask (for example, /24), and ensure that the address is on the same subnet as the gateway (for example, 192.168.1.1). |
IP address conflict (two devices use the same IP address) |
Use an unassigned IP address, or enable automatic address assignment through DHCP (dhclient eth0). |
DHCP failed to obtain an address |
Check whether the DHCP service is running (ps aux|grep dhcp), or manually configure a static IP address to rule out a DHCP server failure. |
Default gateway is missing |
Run ip route show and check for a default via entry. If none exists, add one manually: ip route add default via 192.168.1.1. |
Transmission layer (firewall and ports)¶
Symptom: Ping requests succeed (the ICMP protocol is working), but services such as SSH and HTTP are inaccessible.
Common causes |
Solutions |
|---|---|
Firewall (iptables/nftables) blocking traffic |
Check the rules by running iptables -L -n -v. Temporarily disable the firewall for testing by running systemctl stop firewalld (or iptables -F). |
Service port is not listening or the service is not running |
Run netstat -tulpn | grep 22 to verify that the sshd process is listening. |
Port is in use or the service is bound to the loopback address (127.0.0.1) |
Check the service configuration and ensure that it listens on 0.0.0.0 (all interfaces) rather than 127.0.0.1 (loopback only). |
Application layer (DNS resolution)¶
Symptom: The host at 8.8.8.8 responds to ping, but ping www.baidu.com fails because the domain name cannot be resolved.
Common causes |
Solutions |
|---|---|
DNS server is not configured or is unreachable |
Check /etc/resolv.conf and ensure that nameserver 8.8.8.8 or nameserver 114.114.114.114 is configured. |
Corrupted DNS cache |
Run systemd-resolve –flush-caches (if the systemd-resolved service is used), or restart the network service. |
Public DNS servers outside China are unreachable |
Use a public DNS server in China (for example, 223.5.5.5 or 114.114.114.114) to work around possible network restrictions. |
Perform a quick diagnosis in the following order:
# 1. Check the status of all network interfaces (particularly whether they are UP and RUNNING)
ip addr show
# 2. Check the default gateway IP
route show default
# 3. Ping the gateway (test reachability)
ping -c 4 <gateway_IP_address>
# 4. Check the current DNS configuration
cat /etc/resolv.conf
# 5. Test domain name resolution
nslookup baidu.com
# 6. Check whether iptables/nftables is filtering traffic
sudo iptables -L -n
sudo nft list ruleset
How do I troubleshoot network issues?¶
See the preceding section for the troubleshooting procedure.
What should I do if the Wi-Fi connection fails?¶
Check the hardware and firmware¶
First, ensure that the system can correctly detect the Wi-Fi module.
Verify the Wi-Fi module: Refer to the smart single-board computer hardware manual and verify the Wi-Fi module model and antenna connection.
Check driver loading: Run iw dev in the terminal and check whether the output contains a wlan0 interface. If there is no output, the driver may not be loaded.
Check firmware loading: Run dmesg|grep -i firmware and check for firmware-loading errors (for example, failed to load).
Verify the Wi-Fi mode: Some modules must first be set to STA (station) mode.
Check the network interface and scan for networks¶
If the hardware is operating correctly, check whether the system can detect nearby wireless networks.
Check the interface status: Run ip addr show wlan0 and verify that the interface status is UP. If it is DOWN, run sudo ip link set wlan0 up to enable it manually.
Scan for available networks: Run sudo iw dev wlan0 scan|grep SSID to scan for nearby Wi-Fi networks. If there is no output, there may be a driver or antenna issue.
Use NetworkManager (if installed): Run nmcli dev wifi list to scan for networks.
Check the connection configuration¶
If a network is detected but the connection fails, the configuration is usually the cause.
Verify the SSID and password: An incorrect SSID or password is the most common cause. Verify that both are entered with the correct case.
Check the encryption method: If wpa_supplicant is used, ensure that its configuration matches the router’s encryption method (for example, WPA2-PSK).
Check the wpa_supplicant service: Run ps -ef | grep wpa_supplicant to verify that the service is running.
Check the Wi-Fi frequency band: Verify that the smart single-board computer supports the frequency band in use (for example, 2.4 GHz or 5 GHz).
Check IP address assignment¶
If the connection succeeds but internet access is unavailable, the IP address configuration is usually the cause.
Check the IP address: Run ip addr show wlan0 and check whether a valid IP address (not 169.254.x.x) has been obtained.
Obtain an IP address manually: Run sudo dhclient wlan0 or sudo udhcpc -i wlan0 to request an address manually.
Check the DHCP service: Verify that the router’s DHCP service is enabled and that its address pool is not exhausted.
How do I configure a static IP address for Ethernet?¶
Configure a temporary address with the ip command (takes effect immediately and is lost after a restart)¶
# 1. Check the network interface name (usually eth0 or enp*)
ip addr show
# 2. Add a static IP address to the network interface (for example, 192.168.1.100/24)
sudo ip addr add 192.168.1.100/24 dev eth0
# 3. Enable the network interface (if it was previously down)
sudo ip link set eth0 up
# 4. Add the default gateway (for example, 192.168.1.1)
sudo ip route add default via 192.168.1.1
# 5. Configure DNS (requires editing /etc/resolv.conf)
echo "nameserver 8.8.8.8" | sudo tee -a /etc/resolv.conf
echo "nameserver 114.114.114.114" | sudo tee -a /etc/resolv.conf
Persist the configuration with systemd-networkd¶
Create or edit the network interface configuration file¶
sudo nano /etc/systemd/network/20-eth0-static.network
Enter the following content¶
[Match]
Name=eth0
[Network]
Address=10.66.82.100/23
Gateway=10.66.82.1
DNS=8.8.8.8
DNS=114.114.114.114
Restart the network service¶
sudo systemctl restart systemd-networkd
How do I check network bandwidth?¶
Check the negotiated physical link speed:
ethtool eth0 | grep -E "Speed|Duplex"